home *** CD-ROM | disk | FTP | other *** search
/ IRIX Base Documentation 2002 November / SGI IRIX Base Documentation 2002 November.iso / usr / share / catman / p_man / cat3 / SCSL / ctrsna.z / ctrsna
Encoding:
Text File  |  2002-10-03  |  8.4 KB  |  265 lines
  1.  
  2.  
  3.  
  4. CCCCTTTTRRRRSSSSNNNNAAAA((((3333SSSS))))                                                          CCCCTTTTRRRRSSSSNNNNAAAA((((3333SSSS))))
  5.  
  6.  
  7.  
  8. NNNNAAAAMMMMEEEE
  9.      CTRSNA - estimate reciprocal condition numbers for specified eigenvalues
  10.      and/or right eigenvectors of a complex upper triangular matrix T (or of
  11.      any matrix Q*T*Q**H with Q unitary)
  12.  
  13. SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
  14.      SUBROUTINE CTRSNA( JOB, HOWMNY, SELECT, N, T, LDT, VL, LDVL, VR, LDVR, S,
  15.                         SEP, MM, M, WORK, LDWORK, RWORK, INFO )
  16.  
  17.          CHARACTER      HOWMNY, JOB
  18.  
  19.          INTEGER        INFO, LDT, LDVL, LDVR, LDWORK, M, MM, N
  20.  
  21.          LOGICAL        SELECT( * )
  22.  
  23.          REAL           RWORK( * ), S( * ), SEP( * )
  24.  
  25.          COMPLEX        T( LDT, * ), VL( LDVL, * ), VR( LDVR, * ), WORK(
  26.                         LDWORK, * )
  27.  
  28. IIIIMMMMPPPPLLLLEEEEMMMMEEEENNNNTTTTAAAATTTTIIIIOOOONNNN
  29.      These routines are part of the SCSL Scientific Library and can be loaded
  30.      using either the -lscs or the -lscs_mp option.  The -lscs_mp option
  31.      directs the linker to use the multi-processor version of the library.
  32.  
  33.      When linking to SCSL with -lscs or -lscs_mp, the default integer size is
  34.      4 bytes (32 bits). Another version of SCSL is available in which integers
  35.      are 8 bytes (64 bits).  This version allows the user access to larger
  36.      memory sizes and helps when porting legacy Cray codes.  It can be loaded
  37.      by using the -lscs_i8 option or the -lscs_i8_mp option. A program may use
  38.      only one of the two versions; 4-byte integer and 8-byte integer library
  39.      calls cannot be mixed.
  40.  
  41. PPPPUUUURRRRPPPPOOOOSSSSEEEE
  42.      CTRSNA estimates reciprocal condition numbers for specified eigenvalues
  43.      and/or right eigenvectors of a complex upper triangular matrix T (or of
  44.      any matrix Q*T*Q**H with Q unitary).
  45.  
  46. AAAARRRRGGGGUUUUMMMMEEEENNNNTTTTSSSS
  47.      JOB     (input) CHARACTER*1
  48.              Specifies whether condition numbers are required for eigenvalues
  49.              (S) or eigenvectors (SEP):
  50.              = 'E': for eigenvalues only (S);
  51.              = 'V': for eigenvectors only (SEP);
  52.              = 'B': for both eigenvalues and eigenvectors (S and SEP).
  53.  
  54.      HOWMNY  (input) CHARACTER*1
  55.              = 'A': compute condition numbers for all eigenpairs;
  56.              = 'S': compute condition numbers for selected eigenpairs
  57.              specified by the array SELECT.
  58.  
  59.  
  60.  
  61.  
  62.  
  63.                                                                         PPPPaaaaggggeeee 1111
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. CCCCTTTTRRRRSSSSNNNNAAAA((((3333SSSS))))                                                          CCCCTTTTRRRRSSSSNNNNAAAA((((3333SSSS))))
  71.  
  72.  
  73.  
  74.      SELECT  (input) LOGICAL array, dimension (N)
  75.              If HOWMNY = 'S', SELECT specifies the eigenpairs for which
  76.              condition numbers are required. To select condition numbers for
  77.              the j-th eigenpair, SELECT(j) must be set to .TRUE..  If HOWMNY =
  78.              'A', SELECT is not referenced.
  79.  
  80.      N       (input) INTEGER
  81.              The order of the matrix T. N >= 0.
  82.  
  83.      T       (input) COMPLEX array, dimension (LDT,N)
  84.              The upper triangular matrix T.
  85.  
  86.      LDT     (input) INTEGER
  87.              The leading dimension of the array T. LDT >= max(1,N).
  88.  
  89.      VL      (input) COMPLEX array, dimension (LDVL,M)
  90.              If JOB = 'E' or 'B', VL must contain left eigenvectors of T (or
  91.              of any Q*T*Q**H with Q unitary), corresponding to the eigenpairs
  92.              specified by HOWMNY and SELECT. The eigenvectors must be stored
  93.              in consecutive columns of VL, as returned by CHSEIN or CTREVC.
  94.              If JOB = 'V', VL is not referenced.
  95.  
  96.      LDVL    (input) INTEGER
  97.              The leading dimension of the array VL.  LDVL >= 1; and if JOB =
  98.              'E' or 'B', LDVL >= N.
  99.  
  100.      VR      (input) COMPLEX array, dimension (LDVR,M)
  101.              If JOB = 'E' or 'B', VR must contain right eigenvectors of T (or
  102.              of any Q*T*Q**H with Q unitary), corresponding to the eigenpairs
  103.              specified by HOWMNY and SELECT. The eigenvectors must be stored
  104.              in consecutive columns of VR, as returned by CHSEIN or CTREVC.
  105.              If JOB = 'V', VR is not referenced.
  106.  
  107.      LDVR    (input) INTEGER
  108.              The leading dimension of the array VR.  LDVR >= 1; and if JOB =
  109.              'E' or 'B', LDVR >= N.
  110.  
  111.      S       (output) REAL array, dimension (MM)
  112.              If JOB = 'E' or 'B', the reciprocal condition numbers of the
  113.              selected eigenvalues, stored in consecutive elements of the
  114.              array. Thus S(j), SEP(j), and the j-th columns of VL and VR all
  115.              correspond to the same eigenpair (but not in general the j-th
  116.              eigenpair, unless all eigenpairs are selected).  If JOB = 'V', S
  117.              is not referenced.
  118.  
  119.      SEP     (output) REAL array, dimension (MM)
  120.              If JOB = 'V' or 'B', the estimated reciprocal condition numbers
  121.              of the selected eigenvectors, stored in consecutive elements of
  122.              the array.  If JOB = 'E', SEP is not referenced.
  123.  
  124.  
  125.  
  126.  
  127.  
  128.  
  129.                                                                         PPPPaaaaggggeeee 2222
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136. CCCCTTTTRRRRSSSSNNNNAAAA((((3333SSSS))))                                                          CCCCTTTTRRRRSSSSNNNNAAAA((((3333SSSS))))
  137.  
  138.  
  139.  
  140.      MM      (input) INTEGER
  141.              The number of elements in the arrays S (if JOB = 'E' or 'B')
  142.              and/or SEP (if JOB = 'V' or 'B'). MM >= M.
  143.  
  144.      M       (output) INTEGER
  145.              The number of elements of the arrays S and/or SEP actually used
  146.              to store the estimated condition numbers.  If HOWMNY = 'A', M is
  147.              set to N.
  148.  
  149.      WORK    (workspace) COMPLEX array, dimension (LDWORK,N+1)
  150.              If JOB = 'E', WORK is not referenced.
  151.  
  152.      LDWORK  (input) INTEGER
  153.              The leading dimension of the array WORK.  LDWORK >= 1; and if JOB
  154.              = 'V' or 'B', LDWORK >= N.
  155.  
  156.      RWORK   (workspace) REAL array, dimension (N)
  157.              If JOB = 'E', RWORK is not referenced.
  158.  
  159.      INFO    (output) INTEGER
  160.              = 0: successful exit
  161.              < 0: if INFO = -i, the i-th argument had an illegal value
  162.  
  163. FFFFUUUURRRRTTTTHHHHEEEERRRR DDDDEEEETTTTAAAAIIIILLLLSSSS
  164.      The reciprocal of the condition number of an eigenvalue lambda is defined
  165.      as
  166.  
  167.              S(lambda) = |v'*u| / (norm(u)*norm(v))
  168.  
  169.      where u and v are the right and left eigenvectors of T corresponding to
  170.      lambda; v' denotes the conjugate transpose of v, and norm(u) denotes the
  171.      Euclidean norm. These reciprocal condition numbers always lie between
  172.      zero (very badly conditioned) and one (very well conditioned). If n = 1,
  173.      S(lambda) is defined to be 1.
  174.  
  175.      An approximate error bound for a computed eigenvalue W(i) is given by
  176.  
  177.                          EPS * norm(T) / S(i)
  178.  
  179.      where EPS is the machine precision.
  180.  
  181.      The reciprocal of the condition number of the right eigenvector u
  182.      corresponding to lambda is defined as follows. Suppose
  183.  
  184.                  T = ( lambda  c  )
  185.                      (   0    T22 )
  186.  
  187.      Then the reciprocal condition number is
  188.  
  189.              SEP( lambda, T22 ) = sigma-min( T22 - lambda*I )
  190.  
  191.      where sigma-min denotes the smallest singular value. We approximate the
  192.  
  193.  
  194.  
  195.                                                                         PPPPaaaaggggeeee 3333
  196.  
  197.  
  198.  
  199.  
  200.  
  201.  
  202. CCCCTTTTRRRRSSSSNNNNAAAA((((3333SSSS))))                                                          CCCCTTTTRRRRSSSSNNNNAAAA((((3333SSSS))))
  203.  
  204.  
  205.  
  206.      smallest singular value by the reciprocal of an estimate of the one-norm
  207.      of the inverse of T22 - lambda*I. If n = 1, SEP(1) is defined to be
  208.      abs(T(1,1)).
  209.  
  210.      An approximate error bound for a computed right eigenvector VR(i) is
  211.      given by
  212.  
  213.                          EPS * norm(T) / SEP(i)
  214.  
  215.  
  216. SSSSEEEEEEEE AAAALLLLSSSSOOOO
  217.      INTRO_LAPACK(3S), INTRO_SCSL(3S)
  218.  
  219.      This man page is available only online.
  220.  
  221.  
  222.  
  223.  
  224.  
  225.  
  226.  
  227.  
  228.  
  229.  
  230.  
  231.  
  232.  
  233.  
  234.  
  235.  
  236.  
  237.  
  238.  
  239.  
  240.  
  241.  
  242.  
  243.  
  244.  
  245.  
  246.  
  247.  
  248.  
  249.  
  250.  
  251.  
  252.  
  253.  
  254.  
  255.  
  256.  
  257.  
  258.  
  259.  
  260.  
  261.                                                                         PPPPaaaaggggeeee 4444
  262.  
  263.  
  264.  
  265.